Masterlist Syntax

Contents

1. Introduction
2. Structure
3. Rules & Guidelines
4. Syntax
   1. Silent Comments
   2. Group Lines
   3. Plugin Lines
   4. Message Lines
   5. Masterlist Variables & Variable Lines
   6. Regular Expression Plugin Lines
   7. Web Links
   8. Global Messages
   9. Conditional Expressions
      1. Compound Conditional Expressions
      2. Else Conditional Expressions
5. Conditional Expression Evaluation
   1. Performance
6. Examples

Introduction

This documentation is a complete record of all information on the masterlist syntax, including rules and guidelines on usage, detailed explanations of features and syntaxes, and examples of usage. It is intended for use by BOSS developers rather than as a document that should be read by users.

As BOSS has developed, so too has the masterlist format. This documentation covers all the functionality present in the latest masterlist format supported by the latest release of BOSS, and also details the next version of the masterlist format to be released.

The current release of BOSS is v2.1.0, which supports MF2.2 and MF2.3 (MF = Masterlist Format). The next release of BOSS will be v2.1.1, which will support only MF2.3. As MF2.4 has not yet been created, this documentation will only cover MF2.3 syntax.

Structure

The masterlist is a plain text file encoded in UTF-8 which lists mod plugins, which are files with .esp or .esm extensions, in the order in which they co-exist best. Each plugin may optionally have one or more messages attached to it for display in the BOSS Log. To make managing the masterlist easier, mods are often placed in groups that are often themed. These groups are defined and named in the masterlist, and also provide some sorting functionality for BOSS's User Rules feature.

The masterlist is parsed by BOSS line-by-line, so it is most useful to analyse the structure by the different types of line present:

• A line that defines a plugin's position is a plugin line. In their most basic form, these lines only contain the plugin's filename.
• A line that contains a message to be attached to a plugin is a message line. In their most basic form, message lines contain a message keyword, which tells BOSS what type of message the line contains, and a string of characters which is the message itself. Message lines are positioned below the plugin line of the plugin they attach messages to.
• A line that defines the start and end point of a group is a group line.

A simple example of this structure is: [group line (beginning)]
[plugin line]
[plugin line]
[message line]
[message line]
[plugin line]
[group line (end)]

Rules & Guidelines

The following are some rules and guidelines that should be followed when editing the masterlist.

1. Always use the latest available version of the masterlist format.
2. When including a web link in a message, be sure to use the Web Links syntax.
3. Don't include any formatting in messages. This includes HTML, BBcode and Wiki syntax.
4. Write the keywords in uppercase and indent message lines by two spaces.
5. Use blank lines to separate plugins that are grouped together or where it helps readability.
6. Use silent comments when something may need clarification to others reading the masterlist, such as when a plugin looks like it is misspelled, but is correct, or is put in a special position for compatibility reasons.
7. Only make edits/additions you're confident about - otherwise discuss the issue on the official forum threads.
8. If you're unsure on how to write something in the correct syntax, check this document and don't be afraid to ask other team members for help.
9. When you list Bash Tags for a plugin, separate them using ,  and not just ,. Eg. {{BASH:Graphics,NoMerge}} should be written {{BASH: Graphics, NoMerge}}. This improves readability in the BOSS Log and the masterlist itself.
10. Put variable lines at the top of the masterlist, just under the header.
11. Put global message lines at the top of the masterlist, just under any variable lines.

Syntax

This section details the syntaxes for functionality found at least partially in all masterlist formats.

Note that a colon : must be put after the last keyword on a line, before the plugin or group name or message that follows it, to mark the boundary. While most of the syntax examples below include the colon with the keyword, they are not two parts of the same thing, and this should be kept in mind.

Some general features of MF2:

• Keywords are case-insensitive.
• Whitespace is ignored, except within plugin filenames, group names, message strings and file, version, regex and language condition arguments.

Silent Comments

Silent comments are character strings that are skipped by the BOSS parser and so have no effect on BOSS's output. C++ style comments must start at the beginning of a line. C style comments must start and end at the beginning of lines. Comments may not be used inline. In the table below, [comment] is the comment being made.

Group Lines

As mentioned before, groups are used to provide some order in the masterlist and to allow bulk plugin sorting via User Rules. A group is defined by start and end lines which enclose the plugins to be contained in the group.

In the table above, [name] is the name of the group. The name should be given at both the start and the end, although inclusion at the end is not an absolute requirement. If an ending line does not contain a group name, it does not require a colon.

Plugin Lines

Plugin lines have the simplest of syntaxes. The line should contain only the plugin filename: [plugin]

Plugin lines also have a keyword associated with them, MOD, which can be given before the plugin filename and the two separated by a colon. However, since BOSS assumes that lines with no recognised keywords are plugin lines, the inclusion of the keyword is unnecessary and for the purposes of readability should not be used unless a conditional is used in the plugin line. If the plugin line has a conditional, the MOD keyword should be included between the conditional and the colon.

Message Lines

Message lines are listed under the plugin line of the plugin that they are to be attached to. There are several different types of message line. In the table below, [message] is the message to be attached. Messages have no special syntax unless otherwise noted.

² Bash Tags suggested by BOSS are given in a specific syntax in order for Wrye Bash/Flash/Flash NV to recognise and automatically apply them. The syntax for adding Bash Tags is {{BASH: Tag1, Tag2}}. The syntax for removing Bash Tags is [Tag1, Tag2]. Any number of Bash Tags may be listed for addition or removal. Information on Bash Tags themselves is found in the Wrye Bash, Wrye Flash and Wrye Flash NV Readmes.

Masterlist Variables & Variable Lines

Variables may be set in the masterlist using the following syntax, where [name] is the variable name: SET: [name]

The name of a variable is a string that must not contain whitespace or a closing parenthesis ). The existence of variables may be queried in conditionals. They are intended for use as shorthand for more complex conditionals that are repeated several times throughout the masterlist, not as a method to track some sort of status, which is why they can only be set, not unset.

Unlike message lines, variable lines exist independently of plugin lines. A variable line will therefore signal the termination of a set of attached message lines, much like a plugin line would, and any message lines after the variable line will be skipped, having no plugin to attach to. For example: [plugin line]
[message line 1]
[message line 2]
[variable line]
[message line 3]

In the above structure, only message lines 1 and 2 will be parsed, and message line 3 will be ignored.

Variable lines are applied after the masterlist has been parsed, before the evaluation of other conditionals.

Regular Expression Plugin Lines

Regular expressions may be used in the masterlist for plugin names using the following syntax, where [regular expression] is the plugin filename written in the POSIX Extended regular expression syntax: REGEX: [regular expression]

BOSS will search the user's plugins and sort all the plugins that match the regular expression given in its location in the masterlist. If more than one plugin matches, the order in which the plugins will be placed at that position is random, so it should not be used to sort a set of similarly named plugins which require specific ordering within the set.

Web Links

URLs in messages will be turned into hyperlinks in the HTML-format BOSS Log if they are enclosed in double quotes. The full URL, including protocol identifier, is required for the URL to be detected as such. URLs in messages can be given labels by including a space followed by the label within the quoted string after the URL itself. Recognised protocol identifiers are:

• http
• https
• file

Examples: "http://www.example.com"

becomes:

http://www.example.com

becomes:

example link

example link ("http://www.example.com")

in the plain text BOSS Log.

Global Messages

A global message may be displayed using the following syntax: GLOBAL [message keyword]: [message]

Where the [message keyword] and [message] are as described in the above Message Lines section. Global messages are not attached to plugins, but are instead displayed in a separate section of the BOSS Log.

Conditional Expressions

A line can be made to be applied only under certain circumstances by adding a conditional expression to the start of that line. Conditional expressions can be added to any line. The syntax for a conditional expression with only one condition is: [condition keyword] [condition] [line]

If [line] is a plugin line, then the conditional must be followed by the MOD keyword, eg. IF FILE("Foo.esp") MOD: MyPlugin.esp will place MyPlugin.esp in that position if Foo.esp is installed.

If [line] is a group line, then the plugins and groups it contains will only be evaluated if the conditional expression evaluates to true, otherwise they will be skipped.

There are two condition keywords available:

There are several types of condition that can be tested for, detailed in the table below.

The syntaxes for the different types of condition variable are:

Filenames, checksums, regular expressions and languages are case-insensitive. Version strings and masterlist variables are case-sensitive.

In addition to explicitly referencing files, there are some placeholders that can be used to reference certain files, given in the table below. These placeholders may be used as [file] variables, but not as any other variable type, including [regex] variables.

The paths referenced are given relative to the folder in which the game's plugins are stored. The game and script extender placeholders will only work if BOSS is running for the relevant game, even if the file they reference is present when running for another game, e.g. using the TES5 placeholder when not running for Skyrim will cause the condition to return false even if the executable is present.

Note: Morrowind's Script Extender is not required if the user has the Morrowind Graphics Extender installed, as the latter includes the former within its own library files (but not for all releases). As such, it is not possible to check conclusively for the existence or for the version of the Morrowind Script Extender.

Compound Conditional Expressions

The above conditional syntax is for when only one condition is present in the conditional. However, conditionals are not limited to only containing one condition. A conditional that contains more than one condition is known as a compound conditional.

Compound conditionals are formed by combining two or more conditionals using logical AND or OR operators, the syntax of which are given below.

The conditionals are evaluated incrementally in the order they are read. This means that the operators operate on everything to the left of them as a whole, and the first conditional on their right. This does not follow the standard order of precedence for logical operators.

A compound conditional composed of four conditions and attached to a line has the syntax: A [operator] B [operator] C [operator] D [line]

where A, B, C and D all represent the syntax: [condition keyword] [condition]

If the operators were such that the expression was A && B || C && D, it would be evaluated as ((A && B) || C) && D, not (A && B) || (C && D).

Else Conditional Expressions

The else conditional expression can be used when a line should be conditional on the opposite of the conditional expression for the previous line of the same type. The syntax is: ELSE [line]

The else conditional may not be used on group lines, the first line of each type in the masterlist, the first plugin line following a group start line, or the first message line following a plugin line.

The previous line of the same type does not have to contain a conditional: but in this case the else conditional will always evaluate to false. Else conditionals may not be used within compound conditionals.

Conditional Expression Evaluation

Evaluation of conditionals attached to lines is deferred until after the masterlist is parsed, for greater flexibility. Evaluation of conditionals does not occur wholly in the order in which they were parsed, but rather in the following order:

1. Variable lines, in the order in which they were parsed.
2. Global message lines, in the order in which they were parsed.
3. Group, plugin, regular expression and message lines, in the order in which they were parsed.

As such, a group's conditional expression does not affect any variable or global message lines contained within that group, and all variables that will be defined for a user's install will already be defined by the time that any non-variable lines get their conditionals evaluated. For example: SET: Var1 IF VAR(Var2) MOD: Var2Mod.esm IF VAR(Var1) SET: Var2 IF VAR(Var2) MOD: Var2Mod.esp

Var1 is set first, then Var2 is set, then the conditional for Var2Mod.esm is evaluated (to true), then the conditional for Var2Mod.esp is evaluated (to true).

Performance

The more conditional expressions that BOSS has to parse, the longer it will take to run. Evaluation of conditional expressions is typically the bottleneck that lengthens execution time. It is therefore important to consider performance when using conditionals. Here are some guidelines to improving performance when using conditionals, in the order of their effectiveness:

1. Use conditional groups wherever you have more than at least four plugins in the same location of the masterlist that share at least one conditional. In practice, four is probably slightly too few plugins to justify a group, since it increases the length of the masterlist. Use your judgment, and ask if you are not sure.
2. If multiple lines throughout the masterlist use the same conditional, and that conditional is not a single variable condition, use that conditional to define a masterlist variable, and change the rest of the lines that use that conditional to instead use a conditional that only contains a variable condition. For example: IF VERSION("Mod1.esp", "1.2", =) MOD: Mod2.esp IF VERSION("Mod1.esp", "1.2", =) MOD: Mod3.esp ... IF VERSION("Mod1.esp", "1.2", =) MOD: Mod4.esp IF VERSION("Mod1.esp", "1.2", =) MOD: Mod5.esp

   is better written as: IF VERSION("Mod1.esp", "1.2", =) SET: Mod1 ... IF VAR(Mod1) MOD: Mod2.esp IF VAR(Mod1) MOD: Mod3.esp ... IF VAR(Mod1) MOD: Mod4.esp IF VAR(Mod1) MOD: Mod5.esp

3. Use else conditional expressions wherever possible. Evaluating an IF/ELSE or IFNOT/ELSE pair of lines requires very nearly half the computation that an IF/IFNOT or IFNOT/IF pair of lines requires.
4. Use file conditions instead of regular expression conditions wherever possible.
5. Use version conditions instead of checksum conditions wherever possible. A version condition can often be used to check if a plugin came from a certain release of a mod, while a checksum condition can be used to check if that plugin was also modified by the user. If you do not require the extra precision, and the version information of the plugin changes consistently between releases, use a version condition and not a checksum condition.

The different types of condition in order of decreasing speed are:

1. Variable conditions: These are very fast as BOSS stores defined masterlist variables in a hash set while running.
2. Plugin active status conditions: The contents of plugins.txt is loaded whether or not there are any plugin active status conditions in the masterlist, and the contents are stored in a hashset after loading, so these conditions are of the same speed as variable conditions.
3. File conditions: These are still fast, and should not impact performance. However, repeated usage may cause slowdown as file existence is not stored in memory and is re-checked for every condition.
4. Regular expression conditions: These are of variable speed, but will always be slower than file checks. They need to scan a directory's contents for any files that match the given regex, so the processing time will vary with the number of files to be scanned. Directory contents is not cached, so repetition of a regex condition can impair performance significantly.
5. Version conditions: These are of a medium speed. They need to read part of a file's contents to extract its version and so are slower than file conditions. Like file existence, version information is not stored in memory.
6. Checksum conditions: These are very slow, though processing time varies with file size. They require a complete read of a file and calculate the CRC from its contents. Usage will result in noticeable slowdown. Calculated CRCs are cached while running so that a plugin's CRC is only calculated a maximum of once. Subsequent checks will be faster than file checks but still slower than variable checks.

Examples

Below are some examples of the syntaxes covered in this documentation. The examples use some real plugins, but the content is purely exemplary and does not necessarily contain any valid information. IF VERSION("BOSS", "2.1.1", <) GLOBAL ERROR: An update to BOSS is available. Please download BOSS v2.1.1. //Make a variable for if OOO is installed. //We can indent this comment because in MF2 whitespace doesn't matter, so it looks like it's at the start of the line. IF FILE("Oscuro's Oblivion Overhaul.esm") && IF FILE("Oscuro's Oblivion Overhaul.esp") SET: OOO //Also make a variable for FCOM: IF FILE("FCOM_Convergence.esp") SET: FCOM Mart's Monster Mod for OOO.esm IFNOT VAR(OOO) WARN: Oscuro's Oblivion Overhaul.esm missing. Re-install OOO. //The above line will only be shown in the BOSS Log if OOO is not installed correctly. Unofficial Oblivion Patch.esp IF VERSION("Unofficial Oblivion Patch.esp", "3.3", <) SAY: Upgrade to the latest version of the UOP Supplementals, found here: "http://oblivion.nexusmods.com/mods/27710" TAG: {{BASH: Relev}} and [NoMerge]. Wrye Bash will automatically add the Relev tag and remove the NoMerge tag for you. IF CHECKSUM("FastExit2.dll", CACF51FC) SAY: You have a legitimate copy of Fast Exit 2 installed. Good on you! All Natural.esp IF VERSION("OBSE", "0.0.20.0", >) WARN: You have the correct version of OBSE installed. Unofficial Shivering Isles Patch.esp IF CHECKSUM("Unofficial Oblivion Patch.esp", E0DDDD00) SAY: You are using version 3.3.5 of the UOP. //The given checksum is the checksum of v3.3.5, as calculated by BOSS. IF VERSION("sr_Oblivion_Stutter_Remover.dll", "4.1.0.0", =) SAY: You have Oblivion Stutter Remover v4.1 installed. //Comment out the below section. /* PluginNotParsed.esp TAG: {{BASH: Graphics}} You'll never see this in your BOSS Log. */ IF VAR(FCOM) MOD: Mart's Monster Mod - Fran's Leveled Quests.esp IF VAR(FCOM) ERROR: Delete. Already integrated into FCOM.

Assuming that all version and plugin conditionals evaluate to true apart from the first, the above would have the following output.

• Mart's Monster Mod for OOO.esm
• Unofficial Oblivion Patch.esp
  • Note: Upgrade to the latest version of the UOP Supplementals, found here: http://oblivion.nexusmods.com/mods/27710
  • Bash Tag suggestion(s): {{BASH: Relev}} and [NoMerge]. Wrye Bash will automatically add the Relev tag and remove the NoMerge tag for you.
  • Note: You have a legitimate copy of Fast Exit 2 installed. Good on you!
• All Natural.esp
  • Warning: You have the correct version of OBSE installed.
• Unofficial Shivering Isles Patch.esp
  • Note: You are using version 3.3.5 of the UOP.
  • Note: You have Oblivion Stutter Remover v4.1 installed.
• Mart's Monster Mod - Fran's Leveled Quests.esp
  • Error: Delete. Already integrated into FCOM.

License

This document is part of the BOSS documentation.
Copyright (C) 2011 BOSS Development Team.
See the file BOSS ReadMe.html for copying conditions.